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25. Maintaining Large Systems 



When a program gets large, it is often desirable to split it up into several files. One reason 
for this is to help keep the parts of tlie program organized, to make things easier to find. It's 
also useful to have the program broken into small pieces tliat are more convenient to edit and 
compile. It is particularly important to avoid the need to recompile all of a large program every 
time any piece of it changes; if the program is broken up into many files, only tlie files that 
have changes in them need to be recompiled. 

The apparent drawback to splitting up a program is that more commands are needed to 
manipulate it. To load the program, you now have to load several files separately, instead of just 
loading one file. To compile it, you have to figure out which files need compilation, by seeing 
which have been edited since they were last compiled, and then you have to com.pilc tliose files. 

What's even more complicated is tliat files can have intcrdependcncies. You might have a file 
called DBFS tliat contains some macro definitions (or flavor or structure definitions), and fi.mctions 
in other files might use those macros, 'lliis means tliat in order to compile any of diose other 
files, you must first load die file DBFS into the Lisp environment so that tlie macros will be 
defined and can be expanded at compile time. You have to remember tJiis whenever you compile 
any of those files. Furthermore, if DBFS has changed, other files of the program may need to be 
recompiled because tlie macros may have changed and need to be re-expanded. 

This chapter describes the syslcm facility, which lakes care of all diese Uiings for you. The 
way it works is that you define a set of files to be a system, using the defsystem special form, 
described below. 1 his system definition says which files make up the system, which ones depend 
on the presence of others, and so on. You put this system definition into its own little file, and 
Uien all you have to do is load thai file and tlie Lisp environment will know about your system 
and what files are in it. You can tlien use the make -system funcdon (see page 526) to load in 
all the files of die system, recompile all the files diat need compiling, and so on. 

The system facility is very general and extensible. This chapter explains how to use it and 
how to extend it. This chapter also explains the patch facility, which lets you conveniendy update 
a large program with incremental changes. 

25.1 Defining a System 

defsystem name {keyword args...)... Special Form 

Defines a system named name. The options selected by die keywords are explained in 
detail later. In general, Uiey fall into two categories: properties of die system and 
transformations. A transformation is an operation such as compiling or loading that takes 
one or more files and does something to them. The simplest system is a set of files and a 
transformation to be performed on tiiem. 

Here are a few examples. 
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(defsystem mysys 

( :compile-load ("AI: GEORGE; PROGi" "AI : GE0RG2; PR0G2"))) 

(defsystem zmail 

( : ndiiit:; ciAa i i j 

(: pathname-default "AI: ZMAIL;") 

( :package zwei ) 

{ rmodule defs "DEFS") 

{ :module mult "MULT" :package tv) 

{:module main ("TOP" "COMNDS" "MAIL" "USER" "WINDOW" 

"FILTER" mult "COMETH")) 
( :compile-load defs) 
( : compile-load main (rfasload defs))) 

{defsystem bar 

(rmodule reader-macros "RDMAC") 
(:module other-macros "MACROS") 
( :module main-program "MAIN") 
( :compile-load reader-macros) 

( :compile-load other-macros (:fasload reader-macros)) 
(: compile-load main-program (ifasload reader-macros 

other-macros) ) ) 

The first example defines a new system called mysys, which consists of two files, both of 
which ;^re to hc comniled and loaded. ITie second example is somewhat more complicated. >fVhat 
all tlie options mean will be specified shortly, but the primary difference is that there is a file 
DEFS which must be loaded before the rest of tlie files (main) can be compiled. The final 
example has two levels of dependency, reader -macros must be compiled and loaded before 
other-macros can be compiled. Both reader-macros and other-macros must then be loaded 
before main -program can be compiled. 

The defsystem options other than transformations are: 
:name Specifies a "pretty" version of the name for the system, for use in printing. 

:short-name 

Specified an abbreviated name used in constructing disk label comments and in patch file 
names for some file systems. 

:component -systems 

Specifies the names of other systems used to make up this system. Performing an 
operation on a system with component systems is equivalent to perfonning the same 
operation on all the individual systems. The format is (xomponent-systems names...). 

:package 

Specifies the package in which transformations are performed. A package specified here 
will override one in the - * - line of the file in question. 

pathname -default 

Gives a local default within the definition of the system for strings to be parsed into 
pathnames. Typically this specifies the directory, when all the files of a system are on the 
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same directory. 

:warnings-default 

Gives a default for the file to use to store compiler warnings in. when make-systemis 
used with tlie :batch option. 

:patchable 

Makes the system be a patchable system (see section 25.7, page 531). An optional 
argument specifies the directory to put patch files in. The default is the pathname- 
default of the system. 

:initial -status 

Specifics what the status of the system should be when make-system is used to create a 
new major version. The default is :experimental. See section 25.7.5, page 536 for further 
details. 

:not- in -disk-label 

Make a patchable system not appear in tlie disk label comment. ITiis should probably 
never be specified for a user system. It is used by patchable systems internal to the main 
Lisp system, to avoid cluttering up tlie label. 

:default-binary-file-type 

Specifies tlie file type to use for compiled IJsp files. The value you specify should be a 
string. If you do not specify this, the standard file type "QFASL" is used. 

:module 

Allows assigning a name to a set of files within the system. ITiis name can then be used 
instead of repeating the filenames. The format is (:module name files options...), files is 
usually a list of filenames (strings). In general, it is a module-specification, which can be 
any of the following: 

a string 

This is a file name. 

a symbol 

This is a module name. It stands for all of the files which are in that module of 
this system. 

an external module component 

This is a list of the form {system-name module-names...), to specify modules in 
another system. It stands for all of the files which are in all of those modules. 

a list of module components 

A module component is any of the above, or the following: 

a list of file names 

This is used in the case where the names of the input and output files of a 
transformation are not related according to the standard naming conventions, for 
example when a QFASL file has a different name or resides on a different 
directory than the source file. The file names in the list are used from left to 
right, thus the first name is the source file. Each file name after the first in the 
list is defaulted from the previous one in the list 
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To avoid syntactic ambiguity, this is allowed as a module component but not as a 
module specification. 

The currently defined options for the :module clause are 

:package Overrides any package specified for the whole system for transformations 

performed on just this module. 

In the second defsystem example above, there are three modules. Each of the first two 
has only one file, and tlie third one (main) is made up both of files and another module. 
To tiike examples of the other possibilities, 

(:module prog ( { "AI : GEORGE; PROG" "AI : GE0RG2; PROG"))) 

(:module foe (defs (zmail defs))) 
The prog module consists of one file, but it lives in two directories, GEORGE and 
GEORG2. If this were a Lisp program, tliat would mean tliat the file "AI: GEORGE; 
PROG >" would be compiled into "AI: GE0RG2; PROG QFASL". The too module 
consists of two other modules the defs module in the same system, and the defs module 
in the zmail system. It is not generally useful to compile files that belong to other 
systems; thus diis foo module would not normally be die subject of a transformation. 
However, dependencies (defined below) use modules and need to be able to refer to 
(depend on) modules of other systems. 

si iset-system-source-f lie sysiem-name filename 

This function specifies which file contains the defsystem for the system system-name, 
filename can be a pathname object or a string. 

Sometimes it is useful to say where the definition of a system can be found without 
taking time to load that file. If make-system is ever used on that system, the file whose 
name has been specified will be loaded automatically. 

25.2 Transformations 

Transformations are of two types, simple and complex. A simple transformation is a single 
operation on a file, such as compiling it or loading it. A complex transformation takes the output 
from one transfonnation and performs another transformation on it, such as loading the results of 
compilation. 

The general format of a simple transformation is [name input dependencies condition), input is 
usually a module specification or another transformation whose output is used. The transformation 
name is to be performed on all the files in the module, or all the output files of the other 
transformation. 

dependencies and condition are optional. 

dependencies is a transformation specification, either a list {transformation- name module- 
names...) or a list of such lists. A module-name is either a symbol that is the name of a module 
in the current system, or a list (system-name module- names...). A dependency declares that all of 
the indicated transformations m.ust be performed on t_he indicated modules before the current 
transformation itself can take place. Thus in the zmail example above, the defs module must 
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have the :fasload transformation pcrfomied on it before the :compile transformation can be 
performed on main. 

I'he dependency has to be a tranformation tliat is explicitly specified as a transformation in 
the system definition, not just an action that might be performed by anything. 'I hat is, if you 
have a dependency (:fasload foo), it means that (fasload foo) is a tranformation of your system 
and you depend on that tranformation: it does not simply mean tliat you depend on foo's being 
loaded. FurtJiermorc, it doesn't work if (:fasload foo) is an implicit piece of another 
tranformation. For example, the following is correct and will work: 
(defsystem foo 

( rmodule foo "FOO") 

{ :module bar "BAR") 

( :compne-load (foo bar))) 

but this doesn't work: 

(defsystem foo 

( rmodule foo "FOO") 

( rmodule bar "BAR") 

( :module blort "BLORT") 

( :compile-load (foo bar)) 

( :compile-load blort (:fasload foo))) 

because foo's :fasload is not mentioned explicitly (i.e. at top level) but is only implicit in the 
(:compile-load (foo bar)). One must instead write: 
(defsystem foo 

(: module foo "FOO") 

( .-module bar "BAR") 

( :module blort "BLORT") 

( :compile-load foo) 

( :compile-load bar) 

( :compile-load blort (rfasload foo))) 

condition is a predicate which specifies when the transformation should take place. Generally 
it defaults according to the type of the transformation. Conditions are discussed further on page 
530. 

ITie defined simple transformations are: 

ifasload Calls die fasload function to load the indicated files, which must be QFASL files 

whose padinames have canonical type :bln (see section 22.2.3, page 459). The 
condition defaults to si:file-newer-than- installed -p, which is t if a newer version 
of the file exists on the file computer than was read into the current environment. 

:readfile Calls die readfile fianction to read in die indicated files, whose names must have 

canonical type :lisp. Use diis for files that are not to be compiled, condition 
defaults to si:file-newer-than-jnstalled-p. 

:compile Calls die qc-file function to compile die indicated files, whose names must have 

canonical type :lisp. condition defaults to si:file-newer-than-file-p, which 
returns t if die source file has been written more recently than die binary file. 
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A special simple transformation is 

:do-components 

(:do-components dependencies) inside a system with component systems will 
cause the dependencies to be done before anything in tlie component systems. 
This is useful when you have a module of macro files used by all of tlie 
component systems. 

The defined complex transformations are 

:compile-load (:compile-load input compile- dependencies load- dependencies compile- condition load- 
condition) is the same as (:fasload (xompile input compile- dependencies compile- 
condition) load- dependencies load-condition). This is the most commonly-used 
transformation. Everything after input is optional. 

:compile-load-init 

See page 531. 

As was explained above, each filename in an input specification can in fact be a list of strings 
when the source file of a program differs from tlie binary file in more tlian just the file type. In 
fact, every filename is treated as if it were an infinite list of filenames with the last filename, or 
in the case of a single string the only filename, repeated forever at the end. Hach simple 
transfomiation takes some number of input filename arguments and some number of output 
filename arguments. As transfonnations are performed, these arguments are taken from the front 
of the filename list. The input arguments are actually removed and the output arguments left as 
input arguments to the next higher transfonnation. To make tliis clearer, consider the prog 

»>-./^r1i.1ri r.K/-«Yr. KoYlp^ft tViiQ ;/^Qrnr\ll0 - JQaH trancf/vrrnntinn nprfnrrnoH lyn it ThlQ TT)Pan«; that prOQ iS 

given as the input to the :compile transfonnation and the output from this transfonnation is given 
as the input to \hQ :fas!oad transformation. The :compi!e transformation takes one input fi.lenam.e 
argument, the name of a Lisp source file, and one output filename argument, the name of the 
QFASL file. The :fasload transformation takes one input filename argument, the name of a 
QFASL file, and no output filename arguments. So. for the first and only file in the prog 
module, the filename argument list looks like ("Al: GEORGE; PROG" "Al: GEORG2; PROG" 
"Al: GE0RG2; PROG" ...). The :compile transformation is given arguments of "Al: GEORGE; 
PROG" and "Al: GE0RG2; PROG" and tlie filename argument list which it outputs as the 
input to the :fasload transfonnation is ("Al: GEORG2; PROG" "Al: GEORG2; PROG" ...). 
ITie :fasload transformation then is given its one argument of "Al: GE0RG2; PROG". 

Note that dependencies are not "transitive" or "inherited". For example, if module a 
depends on macros defined in module b, and therefore needs b to be loaded in order to compile, 
and b has a similar dependency on c, c will not be loaded during compilation of a. 
Transformations with these dependencies would be written 
( :compile-load a (rfasload b)) 

^./^/~.ml^-l^/-._^r^o/^ h /.foolriarl /»^^ 

To say that compilation of a depends on both b and c, you would instead write 

{ :compi le-load a (ifasload b c)) 

( :compile-load b {:fasload c)) 
If in addition a depended on c (but not b) during loading (perhaps a contains defvars whose 
initial values depend on functions or special variables defined in c) you would write the 
transformations 



SRC:<F.MAN>MAKSYS.TEXT.30 24-JAN-83 



Making a System 526 I Jsp Machine Manual 



{ :compile-load a (:fasload b c) (:fasload c)) 
{ :compi le-load b (:fasload c)) 

25.3 Making a System 

make- system name &rcst keywords 

I'lic make-system function does the actual work of compiling and loading. In the 
example above, if PROGI and PR0G2 have both been compiled recently, then 

(make-system 'mysys) 
will load them as necessary, if either one might also need to be compiled, then 

(make-system 'mysys 'rcompile) 
will do that first as necessary. 

ITie very first thing make-system does is check whether the file which contains the 
def system for the specified system has changed since it was loaded. If so, it offers to 
load the latest version, so that tlie remainder of the make -system can be done using the 
latest system definition. (Ihis only happens if the filctype of that file is LISP.) After 
loading this file or not, make -system goes on to process the files that compose the 
system. 

If the system name is not recognized, make-system offers to load the file SYS: SITE; 
system-tiame SYSTEM, in the hope that that will contain a system definition. 

make-system lists what transfonnations it is going to perform on what files, asks the user 
for confirmation, then perfonns the transformations. Before each transformation a message 
is printed listing the transfonnation being performed, the file it is being done to, and the 
package. This behavior can be altered by keywords. 

^Fhese are the keywords recognized by the make -system fijnction and what they do. 

inoconfirm Assumes a yes answer for all questions that would otherwise be asked of the user. 

:selective Asks the user whether or not to perform each transformation that appears to be 

needed for each file. 

rsilent Avoids printing out each transformation as it is performed. 

:reload Bypasses the specified conditions for performing a transformation. Thus files are 

compiled even if they haven't changed and loaded even if they aren't newer than 
the installed version. 

:noload Does not load any files except those required by dependencies. For use in 

conjunction with the :compjle option. 

.compile Compiles files also if need be. The default is to load but not compile. 

recompile This is equivalent to a combination of :compile and :reload: it specifies 
compilation of all files, even those whose sources have not changed since last 
compiled. 

:no-increment-patch 

When given along with the :compile option, disables the automatic incrementing 
of the major system version that would otherwise take place. See section 25.7, 
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page 531. 

:increment- patch 

Increments a patchable system's major version without doing any compilations. 

See section 25.7, page 531. 

:no-reload -system-declaration 

l\irns off the check for whether tlie file containing the defsystem nhas been 
changed. This file will be loaded only if it has never been loaded before. 

:batch Allows a large compilation to be done unattended. It acts like :noconfirm with 

regard to questions, turns off more-processing and fdefine-warnings (see inhibit- 
fdefine-warnings, page 171), and saves the compiler warnings in an editor buffer 
and a file (it asks you for the name). 

:defaulted -batch 

This is like :batch except that it uses tlie default for tlie pathname to store 
warnings in and does not ask the user to type a pathname. 

:print-only Just prints out what transformations would be performed; does not actually do 
any compiling or loading. 

:noop Is ignored. This is useful mainly for programs that call make -system, so that 

such programs can include forms like 

(make-system 'mysys (if compile-p 'icompile ':noop)) 

25.4 Adding New Keywords to make-system 

make-system keywords arc defined as functions on the si:make-system-keyword property of 
the keyword. 1 he ftinctions are called with no arguments. Some of Lhe relevant variables Lhey 
can use are 

si:*system-being-made* Variable 

The internal data structure that represents the system being made. 

si:*make-system-forms-to-be-evaled-befope* Variable 

A list of forms tliat are evaluated before the transformations are performed. 

si:*make-system-forms-to-be-evaled-after* Variable 

A list of forms that are evaluated after the transformations have been performed. 
Transformations can push entries here too. 

si:*make-system-forms-to-be-evaled-finally* Variable 

A list of forms that are evaluated by an unwind -protect when the body of make-system 
is exited, whether it is completed or not. Closing the batch warnings file is done here. 
Unlike the si: *make-system-forms-to-be-evaled -after* forms, these forms are 
evaluated outside of the "compiler warnings context". 
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si: •query-type* Variable 

Controls how questions are asked. Its normal value is :normal. :noconfirm means no 
questions will be asked and :selective asks a question for each individual file 
transformation. 

si:*silent-p* Variable 

1ft. no messages are printed out. 

si:*batch-inode-p* Variable 

if t, :batch was specified. 

si:*pedo-all* Variable 

If t all transformations are performed, regardless of the condition functions. 

si : ♦top-level -transformations* Variable 

A list of tlie names of transfomiations that will be performed, such as {:fasload :readfile). 

si :*file-transf ormation-f unction* Variable 

The actual function that gets called with the list of transformations tliat need to be 
perfonned. Ihe default is si:do -file-transformations. 

si :def ine-make-system-special-variable variable value Special Form 

[dej\'ar-p] 
Causes variable to be bound to value during the body of the call to make -system. This 
allows you to define new variables similar to those listed above, value is evaluated on 
entry to make -system. If defvar-p is specified as (or defaulted to) t, variable is defined 
with defvar. It is not given an initial value. If defvar-p is specified as nil, variable 
belongs to some other program and is not defvar'cd here. 

The following simple example adds a new keyword to make-system called :just-warn, which 
means that fdefine warnings (see page 169) regarding fimctions being overwritten should be 
printed out, but die user should not be queried. 

(si :define-make-sys tern- special- variable 

inhibit-fdef ine-warnings inhibi t-fdef ine-warnings nil) 

(defun (: just-warn si :make-system-keyword) () 
(setq inhibit-fdef ine-warnings ': just-warn)) 
(See the description of the inhibit-fdefine-warnings variable, on page 171.) 

make-system keywords can do something directly when called, or they can have tiieir effect 
by pushing a form to be evaluated onto si:*make-system-forms-to-be-evaled-after* or one of 
the other two similar lists. In general, die only useful thing to do is to set some special variable 
defined by si;define-make-system-special-variable. In addition to the ones mentioned above, 
user-defined transfonnations may have their behavior controlled by new special variables, which 
can be set by new keywords. If you want to get at the list of transfonnations to be performed, 
for example, die right way is to set si:*file-transformation-function* to a new fijnction, which 
dien can call si:do-file-transformations with a possibly modified list. That is how the :print- 
only keyword works. 
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25.5 Adding New Options for defsystem 

Options to defsystem arc defined as macros on the si:defsystem -macro property of the 
option keyword. Such a macro can expand into an existing option or transformation, or it can 
have side effects and return nil. I'here arc several variables Lhcy can use; the only one of general 
interest is 

si: ♦system-being-defined* Variable 

The internal data structure tliat represents the system that is currently being constructed. 

si:define-defsystem-special-variable variable value Special Fonn 

Causes value to be evaluated and variable to be bound to the result during the expansion 
of the defsystem special form. This allows you to define new variables similar to the one 
listed above. 

sirdefine-simple-transformation Special Form 

This is the most convenient way to define a new simple transformation. The form is 
{ si :def ine-simple-transformation name Junction 
default- condition input- file- types output- file- types 
pretty-names compile-like load-like) 

For example, 

(si :def ine-simple-transformation :compile si:qc-file-l 
si:file-newer-than-file-p ("LISP") ("QFASL")) 
input- file- types and output- file- types are how a transformation specifies how many input 
filenames and output filenames it should receive as arguments, in this case one of each. 
They also, obviously, specify the default file type for these patlmames. Ihe si:qc-tile-1 
function is mostly like qc-file, except for its interface to packages. It takes input-file and 
output-file arguments, 

pretty-names, compile- like, and load-like are optional. 

pretty-names specifies how messages printed for the user should print the name of the 
transformation. It can be a list of the imperative ("Compile"), tlic present participle 
("Compiling"), and the past participle ("compiled"). Note that die past participle is not 
capitalized, because when used it does not come at the beginning of a sentence, pretty- 
names can be just a string, which is taken to be the imperative, and the system will 
conjugate the participles itself. If pretty-names is omitted or nil it defaults to the name of 
the transformation. 

compile-like and load-like say when the transformation should be performed. Compile-like 
transformations are performed when the xompile keyword is given to make-system. 
Load-like transformations are performed unless the :noload keyword is given to make- 
system. By default compile-like is t but load-like is nil. 

Complex transformations are defined as normal macro expansions, for example, 
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(defmacro ( : compi le-load si : def system-macro) 

(input &optional com-dep load-dep 

com-cond load-cond) 
'(:fasload {:compile .input , com-dep , com-cond) 
, load-dep , load-cond)) 

25.6 More Esoteric Transformations 

It is sometimes useful to specify a transformation upon which something else can depend, but 
which is performed not by default, but rather only when requested because of that dependency. 
ITie transformation nevertheless occupies a specific place in tlie hierarchy. The :skip defsystem 
macro allows specifying a transformation of this type. For example, suppose there is a special 
compiler for the read table which is not ordinarily loaded into the system. The compiled version 
should still be kept up to date, and it needs to be loaded if ever the read table needs to be 
recompiled. 

(defsystem reader 

( :pathname-default "AI: LMIO;") 

(:package system-internals) 

( :module defs "RDDEFS") 

(:module reader "READ") 

(:module read-table-compiler "RTC") 

(rmodule read-table "RDTBL") 

( : compile-load defs) 

( : compile-load reader (:fasload defs)) 

(:skip :fasload (:compile read-table-compiler)) 

( : rtc-compile-load read-table (:fasload read-table-compiler))) 
Assume that there is a complex transformation :rtc -compile -load, which is like :compile-load 
except that is is built on a transfonnation called something like :rtc-compile, which uses the read 
table compiler ratlier tlian the Lisp compiler. In the above system, then, if the :rtc-compile 
transformation is to be performed, the :fasload transformation must be done on read -table- 
compiler first that is the read table compiler must be loaded if the read table is to be 
recompiled. If you say (make -system 'reader ':compile), then the :compile transformation will 
still happen on the read -table -compiler module, compiling the read table compiler if need be. 
But if you say (make-system 'reader), the reader and the read table will be loaded, but die 
:skip keeps tliis from happening to die read table compiler. 

So far nothing has been said about what can be given as a condition for a transformation 
except for the default functions, which check for conditions such as a source file being newer 
than the binary. In general, any function that takes die same arguments as die transformation 
function (e.g. qc-file) and returns t if the transformation needs to be performed, can be in this 
place as a symbol, including for example a closure. To take an example, suppose diere is a file 
diat contains compile-flavor-methods for a system and diat should Uierefore be recompiled if 
any of Uie flavor method definitions change. In diis case, the condition function for compiling 
diat file should return t if eiUier die source of diat file itself or any of die files diat define die 
flavors have changed. This is what die xompile-load-init complex transfonnation is for. It is 
defined like diis: 
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(defmacro ( :compile-load-ini t si :defsystem-macro) 

(input add-dep Soptional com-dep load-dep 
8faux function) 
(setq function {let-closed (( *additional -dependent-modules* 

add-dep) ) 
'compi le-load-i nit-condition) ) 
'(:fasload (:compile , input , com-dep .function) , load-dep)) 

(defun compile-load-init-condition {source-file qfasl-file) 
(or { si : f i le-newer-than-f i le-p source-file qfasl-file) 

(local-declare ({special *additional-dependent-modules*) ) 
{si:other-fi les-newer-than-f i le-p 

♦additional -dependent-modules* 
qfasl-file)))) 
The condition function that will be generated when this macro is used returns t either if si:file- 
newer-than-file-p would with tliose arguments, or if any of the other files in add-dep, which 
presumably is a module specification, are newer dnan the QFASL file. 'Ilius the file (or module) 
to which the :compi!e-load-init transformation applies will be compiled if it or any of die source 
files it depends on has been changed, and will be loaded under the nornial conditions. In most 
(but not all cases), com-dep will be a :fasload transfonnation of the same files as add-dep 
specifies, so that all die files this one depends on will be loaded before compiling it. 

25.7 The Patch Facility 

Wq patch facility allows a system maintainer to manage new releases of a large system and 
issue patches to correct bugs. It is designed to be used to maintain both die Lisp Machine system 
itself and applications systems that are large enough to be loaded up and saved on a disk 
partition. 

When a system of programs is very large, it needs to be maintained. Often problems are 
found and need to be fixed, or other little changes need to be made. However, it takes a long 
time to load up all of die files diat make up such a system, and so radier dian having every user 
load up all die files every dme he wants to use the system, usually die files just get loaded once 
into a IJsp world, which is dien saved away on a disk parution. Users dien use diis disk 
partition, copies of which may appear on many machines. The problem is diat since die users 
don't load up the system every dme diey want to use it, diey don't get all die latest changes. 

ITie purpose of die patch system is to solve this problem. A patch file is a litde file that, 
when you load it, updates the old version of the system into die new version of die system. 
Most often, patch files just contain new function definidons; old ftinctions are redefined to do 
their new thing. When you want to use a system, you first use the Lisp environment saved on 
die disk, and dien you load all die latest patches. Patch files are very small, so loading diem 
doesn't take much dme. You can even load die saved environment, load up die latest patches, 
and dien save it away, to save fijture users die trouble of even loading die patches. (Of course, 
new patches may be made later, and dien diese will have to be loaded if you want to get die 
very latest version.) 
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For every system, tliere is a series of patches that have been made to that system. 1 o get tlie 
latest version of the system, you load each patch file in the series, in order. Sooner or later, the 
maintainer of a system will want to stop building more and more patches, and recompile 
everything, starting afresh. A complete recompilation is also necessary when a system is changed 
in a far-reaching way, that can't be done with a small patch; for example, if you completely 
reorganize a program, or change a lot of names or conventions, you might need to completely 
recompile it to make it work again. After a complete recompilation has been done, the old patch 
files arc no longer suitable to use; loading them in might even break things. 

The way all this is kept track of is by labelling each version of a system with a two-part 
number. The two parts are called tlie major version number and the minor version number. ITie 
minor version number is increased every time a new patch is made; tJie patch is identified by the 
major and minor version number together. The major version number is increased when the 
program is completely recompiled, and at that time the minor version number is reset to zero. A 
complete system version is identified by the major version number, followed by a dot, followed 
by the minor version number. 

To clarify this, here is a typical scenario. A new system is created; its initial version number 
is 1 .0. 1 hen a patch file is created; the version of die program that results from loading the first 
patch file into version 1.0 is called 1.1. llien another patch file miglit be created, and loading 
that patch file into system 1.1 creates version 1.2. I'hen tlie entire system is recompiled, creating 
version 2.0 from scratch. Now tlic two patch files are irrelevant, because they fix old software; 
tlie changes tliat they reflect are integrated into system 2.0. 

Note that the second patch file should only be loaded into system 1.1 in order to create 
system 1.2; you shouldn't load it into 1.0 or any other system besides 1.1. It is important that 
all the patch files be loaded in tlie proper order, for two reasons. First, it is very useful that any 
system numbered 1.1 be exactly the same software as any other system numbered 1.1, so that if 
somebody reports a bug in version 1.1, it is clear just which software is being complained about. 
Secondly, one patch might patch another patch; loading them in some other order might have 
the wrong effect. 

The patch facility keeps track of all the patch files that exist, remembering which version each 
one creates. There is a separate numbered sequence of patch files for each major version of each 
system. All of them are stored in the file system, and tlie patch facility keeps track of where they 
all are. In addition to the patch files themselves, there are "patch directory" files that contain the 
patch facility's data base by which it keeps track of what minor versions exist for a major version, 
and what the last major version of a system is. These files and how to make them are described 
below. 

In order to use the patch facility, you must define your system with defsystem (see chapter 
25, page 520) and declare it as patchable with die :patchable option. When you load your 
system (with make-system, see page 526), it is added to the list of all systems present in the 
world. The patch facility keeps track of which version of each patchable system is present and 
where the data about diat system reside in the file system. This information can be used to 
update the Lisp world automatically to the latest versions of all die systems it contains. Once a 
system is present, you can ask for the latest patches to be loaded, ask which patches are already 
loaded, and add new patches. 
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You can also load in patches or whole new systems and then save the entire Lisp environment 
away in a disk partition. This is explained on section 32.10, page 651. 

When a Lisp Machine is booted, it prints out a line of infonnation telling you what systems 
arc present, and which version of each system is loaded. This information is returned by tlie 
function si:system-version-info. It is followed by a text string containing any additional 
infonnation that was requested by whomever created tlic current disk partition (sec disk -save, 
page 654). 

print-system-modif ications &rest system-names 

With no arguments, this lists all the systems present in this world and, for each system, 
all the patches tliat have been loaded into this world. For each patch it shows tlie major 
version number (which will always be die same since a world can only contain one major 
version), the minor version number, and an explanation of what tlie patch does, as typed 
in by tlie person who made the patch. 

If print-system -modifications is called with arguments, only the modifications to the 
systems named are listed. 

si :get-system-version &optional system 

Returns two values, tlie major and minor version numbers of the version of system 

currently loaded into the machine, or nil if diat system is not present, system defaults to 
"System". 

si : system- version -info &optional (brief-pnW) 

Thi<; rornrns a string giving information about which systems and what versions of the 
systems are loaded into the machine, and what microcode version is running. A typical 
string for it to produce is: 

"System 91.31, ZMai 1 48.5, Daedalus 1.4, microcode 204" 
If brief-p is t, it uses short names, suppresses die microcode version, any systems which 
should not appear in die disk label comment, die name System, and the commas: 

"91.31 Daed 1.4" 

25.7.1 Defining a System 

In order to use die patch facility, you must declare your system as patchable by giving die 
:patchable opdon to defsystem (see chapter 25, page 520). The major version of your system in 
die file system will be incremented whenever make- system is used to compile it. Thus a major 
version is associated with a set of QFASL files. The major version of your system diat is 
remembered as having been loaded into the Lisp environment will be set to the major version in 
die file system whenever make -system is used to load your system and die major version in die 
file system is greater dian what you had loaded before. 

After loading your system, you can save it with die disk -save function (see page 654). disk- 
save will ask you for any additional information you want printed as part of the greeting when 
die machine is booted. ITiis is in addition to the names and versions of all die systems present in 
diis world. If die system version will not fit in die 16-character field allocated in die disk label, 
disk-save will ask you to type in an abbreviated form. 
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25.7.2 Patch Hies 

'rhc patch system will maintain several different types of files in the directory associated with 
your system. This directory is specified to defsystem via either the :patchable option or die 
:pathname-default option. These files arc maintiiincd automatically, but so that you will know 
what they are and when they arc obsolete (because they are associated with an obsolete version of 
your system), they arc described here. 

llie file that tells the system's current major version has a name of die forni Al: MYDIR; 
PATCH (PDIR) (on Tops-20, OZ:PS:<MYDIR> PATCH.DIRECTORY), where the host, device, 
and directory (AhMYDIR; or OZ:PS:<MYDIR> in this example) come from the system definition 
as explained above. 

For each major version of the system, there is a patch directory file , of the fonn Al: MYDIR; 
PAT259 (PDIR), which describes die individual patches for that version, where 259 is tlie major 
version number in Uiis example. (On rops-20, tJiis is OZ:PS:<MYDIR> PATCH - 
259.DIRECTORY). 

Then for each minor version of the system, the source of the patch file itself has a name of 
die form Al: MYDIR; P59.69 >, for minor version 69 of major version 259. Note that 259 has 
been truncated to 59 to fit into six characters for ITS. On Tops-20 this would be 
OZ:PS:<MYDIR> PATCH -259- 69.LISP. Patch files get compiled, so there will also be files fike 
Al: MYDIR; P59.69 QFASL (on rops-20, OZ:PS:<MYDIR> PATCH- 259 -69.QFASL). 

If die :patchable option to defsystem is given an argument, telling it to put the patch files 
in a different directory than die one which holds die other files of die system, Uien a slightly 
different set of file name conventions are used. 

On ITS, the file diat tells die current major version is of die form Al: PATDIR; system 
(PDIR), where systerji is die name of die system and PATDIR is die directory specified in die 
:patchable option to defsystem. 1 he patch directory file for major version nnn is of the form 
Al: PATDIR; sysnnn (PDIR), where sys is die short name specified with die :short-name option 
to defsystem. A patch file has a name of die form Al: PATDIR; nnn. mm; note Uiat die major 
version is truncated to three digits instead of two. In diis set of file name conventions, die patch 
files don't all fall together in alphabetical order, as diey do in the first set. 

On rOPS-20, die file names take die fonns OZ:PS:<PATDIR>5>'5/e//2 .PATCH -DIRECTORY, 
OZ:PS:<PATDIR>5F57(?/?; -««//. PATCH -DIRECTORY, and OZ:PS:<PATDIR>5>'5/ew-/2/i/2- 
mmm. LISP (or .QFASL). TTiese file name conventions allow the patches for muldple systems to 
coexist in die same directory. 
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25.7.3 Loading Patches 

load-patches &rcst options 

This fiinction is used to bring the current world up to die latest minor version of 

wiiiLiiC vCi iiJdjvJi vCi:5iV-/ii it o, lui an D^btviiio j^i vbvnt, v/i »v^i wvi cum r^pvumwU Sjf ol\^hj3. li 

diere are any patches available, load -patches will offer to read diem in. With no 
arguments, load -patches updates all die systems present in this world. 

options is a list of keywords. Some keywords are followed by an argument. The 
following options are accepted: 

:systems list list is a list of names of systems to be brought up to date. If diis option 
is not specified, all systems are processed. 

:verbose Prints an explanation of what is being done. This is the default. 

:selective For each patch, says what it is and then ask die user whether or not to 

load it. This is die default. If die user answers P, selective mode is 
turned off for any remaining patches to die current system. 

:noselective Turns off :selective. 

:silent Turns off both :selective and :verbose. In :silent mode all necessary 

patches are loaded without printing anything and without querying the 
user. 

:force-unfinished 

Loads patches that have not been finished yet, if diey have been 
compiled. Iliis is useful for testmg a patch before releasmg it to ail die 
users. 

load -patches returns t if any patches were loaded. 

Currently load -patches is not called automatically, but the system may be changed to offer 
to load patches when die user logs in, in order to keep diings up to date. 

25.7.4 Making Patches 

There are two editor commands diat are used to create patch files. During a typical 
maintenance session on a system you will make several edits to its source files. The patch system 
can be used to copy diese edits into a patch file so that diey can be automatically incorporated 
into die system to create a new minor version. Edits in a patch file can be modified funcdon 
definitions, new functions, modified defvar's and defconst's, or arbitrary forms to be evaluated, 
even including load's of new files. 

Meta-X Add Patch adds die region (if diere is one) or die current "defun" to die patch file 
currently being constructed. The first dme you give diis command it will ask you what system 
you are patching, allocate a new minor version number, and start construcdng die patch file for 
diat version. If you change a ftjnction, you should recompile it, test it, dien once it works use 
Add Patch to put it in die patch file. 
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1^he patch file being constructed is in an editor buffer. If you mistakenly Add Patch 
something that doesn't work, you can select the buffer containing tlie patch file and delete it. 
Then later you can Add Patch tlie corrected version. 

While you are making your patch file, the minor version number that has been allocated for 
you is reserved so that nobody else can use it. 'Iliis way if two people are patching a system at 
the same lime, they will not both get the same minor version number. 

After making and testing all of your patches, use Meta-X Finish Patch to install tlie patch 
file so tliat other users can load it. This will compile tlie patch file if you have not done so 
yourself (patches are always compiled), it will ask you for a comment describing the reason for 
tlie patch; load-patches and print -system -modifications print these comments. 

After finishing your patch, if you do another Add Patch it will ask you which system again 
and start a new minor version. Note that you can be putting together patches only for one 
system at a time. 

You can start a patch without adding anything to it with the Meta-X Start Patch command. 
This does everything that Add Patch docs except put text into tlie patch file. 

If you start to make a patch and change your mind, use the command Meta-X Cancel 
Patch. ITiis will delete the record that says that this patch is being worked on. It will also tell 
the editor tliat you are not editing a patch. 

If you wish to defer finishing the patch until a later session, you should just save the editor 
buffer that contains the patch file. In the next session, use tlie command Meta-X Resume Patch 
to resclect that patch. You will have to specify the minor version number of the patch you wish 
to resume (it would be wrong to assume that your patch is the last one, since someone else might 
have started one). Once you have done this, you are again in a position to use Add Patch or 
Finish Patch or Cancel Patch on this patch. 

You can undo a finished patch by using Resume Patch and then Cancel Patch. 

25.7.5 System Status 

l^he patch system has the concept of die "status" of a major version of a system. The status 
is displayed when the system version is displayed, in places such as the system greeting message 
and the disk partition comment. This status allows users of the system to know what is going on. 
71ie status of a system changes as patches are made to it. 

The status is one of the following keywords: 

:experimental The system has been built but has not yet been fiilly debugged and released to 
users. This is the default status when a new major version is created, unless it is 
overridden with the :initial -status option to defsystem. 

released ITie system is released for general use. ITiis status produces no extra text in the 

system greeting and the disk partition comment. 
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:obsolete The system is no longer supported. 

:broken This is like :experimental, but is used when tiie system was thought incorrectly to 

have been debugged, and hence was :reieased for a while. 

si : set-system-status system status &optional major-version 

Changes the status of a system, system is the name of the system, major-version is Lhe 
number of tJie major version to be changed; if unsupplied it defaults to tlie version 
currently loaded into the Lisp world, status should be one of the keywords above. 
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